home *** CD-ROM | disk | FTP | other *** search
/ Die Speccy' 97 / Die Speccy' 97.iso / amiga_system / the_aminet / comm / bbs / maxshell101.lha / MAXShell.DOC < prev    next >
Text File  |  1995-09-15  |  12KB  |  239 lines
  1.    MAXShell v1.01 - A door for running CLI based programs under M A X's BBS
  2.    ~~~~~~~~~~~~~~
  3.    Based on TrShell, by Timothy Aston. Max's adaption by MPS '95!
  4.  
  5.    At last! Now Max's sysops can access a FULL remote CLI and access the
  6.    huge range of CLI based doors available, such as Hack & Slash, Global
  7.    War 2, and Contris!
  8.  
  9.    This door is pretty much a conversion of the original TAShell for
  10.    TransAmiga BBS, by Timothy Aston (Which used much of the remote CLI
  11.    code from the FIFO distribution), to a Max's compatible door. Extra
  12.    Max's specific functionality has also been added.
  13.  
  14.    To run this door, you will need Matthew Dillon's 'fifo.library' and
  15.    'fifo-handler' installed. Just copy the included 'fifo.library' to
  16.    libs: and 'fifo-handler' to l:, then add 'run >nil: <nil: l:fifo-handler'
  17.    to your user-startup.
  18.  
  19.    Also, make sure your stack is set to at least 32768 for proper operation.
  20.  
  21.    Run like any other door (Function 34), and use the following arguments:
  22.  
  23. Usage: MAXShell [<startup-script>] [-c] [-d] [-e] [-f]
  24. ~~~~~~                                   [-s<substitution char>] [-t]
  25.  
  26.    Where: <startup-script> is an optional shell startup script. Use this for
  27.           running games, etc. An example startup script could be:
  28.  
  29.    -----------------------------CUT HERE-----------------------------
  30.    cd doors:globalwar
  31.    globalwar %f ACCESS %l PAGELENGTH %p TIMELEFT %k
  32.    endcli
  33.    -----------------------------CUT HERE-----------------------------
  34.  
  35.           Max's autoinserts can be used in the script for supplying needed
  36.           parameters to shell programs. (For example, the above will supply
  37.           the user name to Global War, as needed).
  38.  
  39.           Note the ENDCLI - This is very important, or users will exit to
  40.           the shell after quitting Global War!
  41.  
  42.           Also note that all scripts must be in DOORS:MAXSHELL/, and you
  43.           obviously don't supply the path for this reason. The reason I
  44.           did this was Max's Filename/Name/Dest/Path field doesn't have
  45.           much room, so this will save characters!
  46.  
  47.           If a startup script filename isn't supplied, MAXShell will just
  48.           give a shell...
  49.  
  50.           -c is a switch to filter out ^C's from the user. Same goes for
  51.              the -d, -e and -f.
  52.  
  53.           You should always have -c and -d enabled, or users can break out
  54.           of the startup script if they're quick enough, and enter CLI!
  55.  
  56.           -s<substitution char> is a switch to enable an additional
  57.           conversion to the user name (%f). The supplied character will
  58.           replace spaces in the user name. This prevents problems with
  59.           command line parsing and spaces in certain programs. I suppose
  60.           you could have used "%f" instead of %f in the script, but it's
  61.           there if you want the feature!
  62.  
  63.           -t is a switch to enable an additional conversion to the user's
  64.           remaining time (%k). The time value will me made to be 5 minutes
  65.           lower. This will allow the CLI based program to exit (Based on
  66.           this time limit) before the BBS will hang up, avoiding problems.
  67.           Of course, this is only useful if the program supports time limits
  68.           in the first place!
  69.  
  70.    (The usage is also shown when MAXShell isn't run as a door, ie. run from
  71.     the CLI).
  72.  
  73. Examples on BBS use of MAXShell:
  74.  
  75. (Noticed that I made an MS: assign to DOORS:MAXSHELL - This is to save more
  76.  characters in the Filename/Name/Dest/Path field, you'll probably run out of
  77.  space if you don't do something similar!)
  78.  
  79. Global War 2: (Assuning above example gw-startup is in DOORS:MAXSHELL/)
  80. Key:  Function:  Extra:  Lo acc:  Hi acc:
  81.  G       34        0       10      10000  
  82.                                           Filename/Name/Dest/Path:
  83.                                         MS:MAXSHELL GW-STARTUP -c -d -s_ -t
  84. Standard CLI:
  85. Key:  Function:  Extra:  Lo acc:  Hi acc:  Filename/Name/Dest/Path:
  86.  !       34        0      10000    10000   MS:MAXSHELL
  87.  
  88. Notes:     * Make sure you have a standard AmigaDOS shell (I had ZShell
  89. ~~~~~~       in my shell-startup, but will not work with FIFO: as far as
  90.              I could see (In other words, the computer came up with some
  91.              alert, and after I removed 'zsh' from my shell-startup, it
  92.              didn't happen again!)
  93.  
  94.            * Yep, that bug mentioned below (By Tim Aston) does occur in
  95.              my conversion, and yep, you guessed it, I haven't got the
  96.              faintest clue on why it occurs! The solution is to use a
  97.              different FIFO every time by creating the FIFO name via
  98.              something like time() to make it unique every time a new
  99.              one is opened!
  100.              This is what I did in converting, and what was originally
  101.              done in the TA scripts that invoked TaShell (TAShell doesn't
  102.              run stand-alone like MAXShell does).
  103.  
  104.            * If a user drops carrier, the program simply sends a ^C to
  105.              the FIFO shell, and exits. This is not always sufficient to
  106.              stop the running shell program. MAXShell will return
  107.              correctly, but the shell process will still be left running.
  108.              This caused complications with the temporary shell-startup
  109.              script I use (With the converted Max's auto-inserts), as it
  110.              will still be in use (By the non-exiting shell), and thus
  111.              can't be removed or changed (Which I needed to do: when
  112.              another user accesses the door, the converted script must
  113.              reflect the new username). A similar workaround was used as
  114.              above to make a unique temporary filename every time. Don't
  115.              worry about about RAM: filling up though, the problem only
  116.              occurs when someone hangs up, or you twit the user. (And even
  117.              then, only in certain cases). One 'locked-out' file occurs
  118.              for each lost-carrier/twit. (Again, only in certain cases).
  119.              This problem exists in the original TaShell also... If anyone
  120.              knows a better way of handling this I'd like to know!
  121.  
  122.            * Max's special conversion characters (@, |, %) are not
  123.              supported at this time - They were causing many problems,
  124.              so they are printed verbatim. If you want to have support
  125.              them, you can always have a go at modifying this source
  126.              code! % should be reasonably easy to get working
  127.              properly. The only precaution is to make sure that the
  128.              program handles the %<char> across a 'split' between
  129.              blocks of output to the Max's screen... This has been
  130.              implemented for escape codes already.
  131.  
  132.            * Some people have reported 'Stack Overflow' requesters when
  133.              running MAXShell. This seemed to occur only when Max's is
  134.              started from the Workbench, when I investigated the problem.
  135.              As far as I can see, it is because new programs spawned from
  136.              Max's when started from WB only have a stack of 4096 bytes,
  137.              which is not enough for MAXShell. Under CLI, the new program
  138.              spawned from Max's inherits the stack from the parent CLI (That
  139.              Max's was run from). So, run Max's from the CLI (Make sure your
  140.              CLI stack is at least 32768!) and you should have no problems.
  141.  
  142.              As from v1.01, I've compiled the program with the StackExtend
  143.              option, so now, if the program runs out of stack, more should
  144.              be automatically allocated. It should run from WB now!
  145.  
  146.            * Another wierd bug: The CLI process number below MAXShell's
  147.              CLI will be suspended until MAXShell's CLI finishes. God
  148.              knows why, it doesn't seem to harm anything, so I can't be
  149.              bothered figuring this one out! Of course, as above, you
  150.              could always try...
  151.  
  152.            * You might find that Max's Filename/Name/Dest/Path is too
  153.              small for my command line examples. The best way is to make
  154.              an MS: assign and/or rename MAXShell to MS, so to run it,
  155.              only MS:MS is needed for the name, saving valuable characters.
  156.  
  157.            * Some doors require a RAW console for correct keyboard input, and
  158.              don't set the shell to RAW mode automatically (It is an option
  159.              in DLG's shell, so some programmers don't bother). Knot is an
  160.              example of such a game that needs a RAW shell. I've included a
  161.              little utility called MakeRaw, written by Christopher Masto,
  162.              which sets the shell to RAW mode - Just include MR in your
  163.              script, just before running the game. See MR.doc for more info.
  164.  
  165.            * Finally, the user's PAUSE flag is set to OFF during the
  166.              duration of the door (To stop games like Hack & Slash having
  167.              annoying 'Press Return...' prompts every screenfull of text),
  168.              and returned to the user's original setting before exiting to
  169.              the BBS. The PAUSE flag will stay OFF, if the user hangs up or
  170.              is twitted.
  171.  
  172. Contact:   For whatever reason, contact me (Matthew Poole, Alias: MPS) via:
  173. ~~~~~~~~
  174.            EMAIL: mp@deakin.edu.au.
  175.  
  176.            BBS: See advertisement for my BBS below.
  177.  
  178.            MAX'sNET: 86:352/100
  179.  
  180. Finally:   This program is hereby FREEWARE! You need not pay for it, as
  181. ~~~~~~~~   it's just something I hacked up to add a much needed feature
  182.            to Max's BBS! Just be sure to distribute the files/archive as
  183.            is, and if you change it, why not send the alterations you
  184.            made to me, so I could incorporate them into the next version...
  185.  
  186.            I'm curious why someone hasn't done this door for Max's BBS
  187.            before, as it was a pretty straightforward task even for me,
  188.            (Well, I DID have the TAShell source, I suppose...) and I'm
  189.            not what you'd call the best coder in the world, or the most
  190.            knowledgable Max's guy around! Which reminds me, I must thank
  191.            Greg Fitch for putting me on the right track about obtaining
  192.            Max's user values. Call his BBS: Xyonics on (07)808-4806.
  193.  
  194.            I'm also (As you might have guessed!) distributing source as
  195.            well. I hope I start a trend in doing this, as I found it
  196.            difficult to find C source concerning Max's BBS, so would like
  197.            to pass on the knowledge I gained in doing this door. All I
  198.            ask is to credit me if you change the code, etc. and perhaps
  199.            a bit of extra access on your BBS and/or perhaps a free
  200.            registration of a shareware program you wrote.
  201.  
  202. Have fun with MAXShell!
  203.  
  204. Catch ya later,
  205. MPS!
  206.  
  207. Program History:
  208. ~~~~~~~~~~~~~~~~
  209. v1.0     - Initial Release
  210.  
  211. v1.01    - Stack Overflow problem hopefully fixed (Compiled with StackExtend
  212.            option in SAS/C).
  213.          - Some display problems fixed (Partial escape codes, codes
  214.            unsupported by Max's).
  215.          - Improved Docs (Corrected, updated, and in a separate file).
  216.          - Other stuff I've forgotten.
  217.  
  218. BBS Advertisement:
  219. ~~~~~~~~~~~~~~~~~~
  220.  
  221.  
  222.  
  223. Here is the original TrShell.c introduction:
  224. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  225.  TrShell, by Timothy Aston
  226.  
  227.    This is put in the public domain as a simple example of how to use
  228.    transamiga.library with TransAmiga.  This was written with DICE but
  229.    should easily be modified to other compilers.  You should note however,
  230.    that DICE opens most libraries automatically (including fifo.library). 
  231.    SAS users will probably have to generate #pragmas for
  232.    transamiga.library and fifo.library.  fifo.h is included with the FIFO
  233.    distribution.
  234.  
  235.    BTW: Note that there does seem to be a persistent bug in this, it
  236.    doesn't fully release the FIFO, any attempt to restart it with an
  237.    already used FIFO name causes NewShell to hang.  If you can figure out
  238.    why this is, I'd really like to know.
  239.